<!DOCTYPE html>
<html lang="en"><head>
<title>Custom Elements</title>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<link rel="stylesheet" href="spec.css" type="text/css">
<link rel="stylesheet" href="prettify.css" type="text/css">
<link rel="stylesheet" href="http://www.w3.org/StyleSheets/TR/W3C-WD" type="text/css">
</head>

<body>

<div class="head">

<div class="logo">
    <a href="http://www.w3.org/"><img width="72" height="48" src="http://www.w3.org/Icons/w3c_home" alt="W3C"></a>
</div>

<h1>Custom Elements</h1>
<h2 id="working-draft">W3C First Public Working Draft 14 May 2013</h2>
<dl>
<dt>This version</dt>
    <dd><a href="http://www.w3.org/TR/2013/WD-custom-elements-20130514/">http://www.w3.org/TR/2013/WD-custom-elements-20130514/</a></dd>
<dt>Latest version</dt>
    <dd><a href="http://www.w3.org/TR/custom-elements/">http://www.w3.org/TR/custom-elements/</a></dd>
<dt>Latest editor's draft</dt>
    <dd><a href="https://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/custom/index.html">https://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/custom/index.html</a></dd>
<dt>Previous version</dt>
    <dd>none</dd>
<dt>Revision history</dt>
    <dd><a id="log" href="https://dvcs.w3.org/hg/webcomponents/log/tip/spec/custom/index.html">https://dvcs.w3.org/hg/webcomponents/log/tip/spec/custom/index.html</a></dd>
<dt>Participate</dt>
    <dd>Discuss on <a href="http://lists.w3.org/Archives/Public/public-webapps/">public-webapps@w3.org</a> (<a href="http://www.w3.org/2008/webapps/">Web Applications Working Group</a>)</dd>
    <dd><a href="https://www.w3.org/Bugs/Public/enter_bug.cgi?comment=&amp;blocked=14968&amp;short_desc=%5BCustom%5D%3A%20&amp;product=WebAppsWG&amp;component=Component%20Model">File bugs</a> (w3.org's <a href="https://www.w3.org/Bugs/Public/">Bugzilla</a>)</dd>
<dt>Editor</dt>
    <dd class="vcard"><span class="fn">Dimitri Glazkov</span>, <span class="org">Google</span>, &lt;<a class="email" href="mailto:dglazkov@chromium.org">dglazkov@chromium.org</a>&gt;</dd>
</dl>

<p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 2013 <a href="http://www.w3.org/"><abbr title="World Wide Web Consortium">W3C</abbr></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><abbr title="Massachusetts Institute of Technology">MIT</abbr></a>, <a href="http://www.ercim.eu/"><abbr title="European Research Consortium for Informatics and Mathematics">ERCIM</abbr></a>, <a href="http://www.keio.ac.jp/">Keio</a>, <a href="http://ev.buaa.edu.cn/">Beihang</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p>

<hr>

<h2 id="abstract">Abstract</h2>

<p>This specification describes the method for enabling the author to define and use new types of DOM elements in a document.</p>

<h2 id="status">Status of This Document</h2>

<p><em>This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the <a href="http://www.w3.org/TR/">W3C technical reports index</a> at http://www.w3.org/TR/.</em></p>

<p>Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.</p>

<p>This document was published by the <a href="http://www.w3.org/2008/webapps/">Web Applications Working Group</a> as an Editor's Draft. If you wish to make comments regarding this document, please send them to <a href="mailto:public-webapps@w3.org">public-webapps@w3.org</a> (<a href="mailto:public-webapps-request@w3.org?subject=subscribe">subscribe</a>, <a href="http://lists.w3.org/Archives/Public/public-webapps/">archives</a>). All feedback is welcome.</p><p>Publication as an Editor's Draft does not imply endorsement by the <abbr title="World Wide Web Consortium">W3C</abbr> Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.</p>

<p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February 2004 <abbr title="World Wide Web Consortium">W3C</abbr> Patent Policy</a>. <abbr title="World Wide Web Consortium">W3C</abbr> maintains a <a href="http://www.w3.org/2004/01/pp-impl/42538/status" rel="disclosure">public list of any patent disclosures</a> made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential Claim(s)</a> must disclose the information in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section 6 of the <abbr title="World Wide Web Consortium">W3C</abbr> Patent Policy</a>.</p>

</div>

<section class="toc">
<h2 id="toc">Table of Contents</h2>
<ol>
    <li><a href="#about"><span class="section">1</span> About this Document</a></li>
    <li><a href="#dependencies"><span class="section">2</span> Dependencies</a></li>
    <li><a href="#terminology"><span class="section">3</span> Terminology</a></li>
    <li><a href="#custom-element-lifecycle"><span class="section">4</span> Custom Element Lifecycle</a></li>
    <li><a href="#registering-custom-elements"><span class="section">5</span> Registering Custom Elements</a>
    <ol>
        <li><a href="#unresolved-element-pseudoclass"><span class="section">5.1</span> Unresolved Element Pseudoclass</a></li>
    </ol></li>
    <li><a href="#instantiating-custom-elements"><span class="section">6</span> Instantiating Custom Elements</a></li>
    <li><a href="#serializing-and-parsing"><span class="section">7</span> Serializing and Parsing Custom Elements in HTML</a></li>
    <li><a href="#declaring-custom-elements"><span class="section">8</span> Declaring Custom Elements</a></li>
<!--
    <li><a href="#elements-and-dom-interfaces"><span class="section">10</span> Elements and DOM Interfaces</a>
    <ol>
        <li><a href="#the-element-element"><span class="section">10.1</span> The <code>element</code> HTML element</a></li>
    </ol></li>
    <li><a href="#other-languages"><span class="section">11</span> Other Languages</a></li> -->
    <li><a href="#acknowledgements">Acknowledgements</a></li>
</ol>

</section>

<section class="spec">

<h2 id="about">About this Document</h2>

<p>All diagrams, examples, notes, are non-normative, as well as sections explicitly marked as non-normative. Everything else in this specification is normative.</p>

<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in <a href="http://dev.w3.org/2006/xbl2/#refsRFC2119">RFC2119</a>. For readability, these words do not appear in all uppercase letters in this specification.</p>

<p>Any point, at which a conforming UA must make decisions about the state or reaction to the state of the conceptual model, is captured as <a href="http://en.wikipedia.org/wiki/Algorithm">algorithm</a>. The algorithms are defined in terms of processing equivalence. The <dfn id="dfn-processing-equivalence">processing equivalence</dfn> is a constraint imposed on the algorithm implementors, requiring the output of the both UA-implemented and the specified algorithm to be exactly the same for all inputs.</p>

<h2 id="dependencies">Dependencies</h2>

<p>This document relies on the following specifications:</p>

<ul>
    <li><a href="http://www.w3.org/TR/CSS2/">CSS Level 2 Revision 1</a></li>
    <li><a href="http://dev.w3.org/csswg/cssom/">CSSOM</a></li>
    <li><a href="http://www.w3.org/TR/DOM-Level-3-Events/">DOM Level 3 Events</a></li>
    <li><a href="http://www.w3.org/TR/domcore/">DOM4 (DOM Core)</a></li>
    <li><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/">HTML</a></li>
    <li><a href="http://html5.org/specs/dom-parsing.html">DOM Parsing and Serialization</a></li>
    <li><a href="http://ecma-international.org/ecma-262/5.1/">ECMAScript Language Specification</a></li>
    <li><a href="http://www.w3.org/TR/selectors/">Selectors Level 3</a></li>
    <li><a href="http://dev.w3.org/2006/webapi/selectors-api/">Selectors API Level 1</a></li>
    <li><a href="http://www.w3.org/TR/WebIDL/">Web IDL</a></li>
</ul>

</section>

<section class="physics">

<h2 id="terminology">Terminology</h2>

<p><dfn id="dfn-custom-element">Custom element</dfn> is <a href="http://www.w3.org/TR/WebIDL/#dfn-platform-object">platform object</a> whose <a href="http://www.w3.org/TR/WebIDL/#dfn-interface">interface</a> is defined by the author. This <a href="http://www.w3.org/TR/WebIDL/#dfn-interface">interface</a> <strong>must</strong> <a href="http://www.w3.org/TR/WebIDL/#dfn-inherit">inherit</a> from the <a href="http://dom.spec.whatwg.org/#interface-element"><code>Element</code></a> <a href="http://www.w3.org/TR/WebIDL/#dfn-interface">interface</a>. The <a href="http://www.w3.org/TR/WebIDL/#interface-prototype-object">interface prototype object</a> of a <a href="#dfn-custom-element">custom element</a>'s <a href="http://www.w3.org/TR/WebIDL/#dfn-interface">interface</a> is called the <dfn id="dfn-custom-element-prototype">custom element prototype</dfn>.</p>

<p>The <dfn id="dfn-custom-element-name">custom element name</dfn> identifies a <a href="#dfn-custom-element">custom element</a> and is a sequence of <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-microsyntaxes.html#alphanumeric-ascii-characters">alphanumeric ASCII characters</a> that <strong>must</strong> match the <a href="http://www.w3.org/TR/1999/REC-xml-names-19990114/#NT-NCName">NCName</a> production and contain a <var>U+002D HYPHEN-MINUS</var> character. The <a href="#dfn-custom-element-name">custom element name</a> <strong>must not</strong> be one of the following values:</p>
<ul>
    <li><code>annotation-xml</code></li>
    <li><code>color-profile</code></li>
    <li><code>font-face</code></li>
    <li><code>font-face-src</code></li>
    <li><code>font-face-uri</code></li>
    <li><code>font-face-format</code></li>
    <li><code>font-face-name</code></li>
    <li><code>missing-glyph</code></li>
</ul>

<div class="informative">
The list of names above is the summary of all hyphen-containing names from the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#other-applicable-specifications">applicable specifications</a>, namely the <a href="http://www.w3.org/TR/SVG/eltindex.html">SVG</a> and the <a href="http://www.w3.org/TR/MathML/">MathML</a>.
</div>

<p>The <dfn id="dfn-element-definition">element definition</dfn> is an association of a <a href="#dfn-custom-element-name">custom element name</a>, <a href="http://dom.spec.whatwg.org/#concept-element-local-name">local name</a> and a <a href="http://dom.spec.whatwg.org/#concept-element-namespace">namespace</a> with a <a href="#dfn-custom-element-prototype">custom element prototype</a>, and <a href="#dfn-lifecycle-callbacks">lifecycle callbacks</a>.</p>

<h2 id="custom-element-lifecycle">Custom Element Lifecycle</h2>

<p>A <a href="#dfn-custom-element">custom element</a> can go through these changes during its lifetime:</p>
<ol>
    <li><a href="#dfn-custom-element">Custom element</a> is created before its <a href="#dfn-custom-element">custom element definition</a> is associated with the <a href="http://dom.spec.whatwg.org/#concept-document">document</a></li>
    <li><a href="#dfn-element-definition">Definition</a> of a <a href="#dfn-custom-element">custom element</a> is associated with the <a href="http://dom.spec.whatwg.org/#concept-document">document</a></li>
    <li><a href="#dfn-custom-element">Custom element</a> instance is created after its <a href="#dfn-element-definition">definition</a> was associated with the <a href="http://dom.spec.whatwg.org/#concept-document">document</a></li>
    <li><a href="#dfn-custom-element">Custom element</a> is <a href="http://www.whatwg.org/specs/web-apps/current-work/#insert-an-element-into-a-document">inserted into a document</a></li>
    <li><a href="#dfn-custom-element">Custom element</a> is <a href="http://www.whatwg.org/specs/web-apps/current-work/#remove-an-element-from-a-document">removed from the document</a></li>
    <li><a href="#dfn-custom-element">Custom element</a> is garbage-collected.</li>
</ol>

<p>A <a href="#dfn-custom-element">custom element</a> can optionally implement several callbacks that are invoked when the element goes through some of these changes. These callbacks are stored internally as a collection of <a href="http://en.wikipedia.org/wiki/Associative_array">key-value pairs</a> and called <dfn id="dfn-lifecycle-callbacks">lifecycle callbacks</dfn>.</p>

<p>To <dfn id="dfn-transfer-callback">transfer a callback named <em>name</em> from an object property named <em>property</em></dfn> to <a href="#dfn-lifecycle-callbacks">lifecycle callbacks</a>, the user agent <strong>must</strong> run the following steps:</p>
<div class="algorithm">
<dl>
<dt>Input</dt>
    <dd><var>NAME</var>, name of the callback</dd>
    <dd><var>PROPERTY</var>, name of the property</dd>
    <dd><var>OBJECT</var>, the object from which <var>PROPERTY</var> is being transferred</dd>
    <dd><var>LIFECYCLE</var>, the <a href="#dfn-lifecycle-callbacks">lifecycle callbacks</a></dd>
<dt>Output
    </dt><dd>None</dd>
</dl>
<ol>
    <li>Let <var>CALLBACK</var> be the result of <a href="http://es5.github.io/#x8.12.3">getting</a> a property named <var>PROPERTY</var> of <var>OBJECT</var></li>
    <li>If <var>CALLBACK</var> exists and is a <a href="http://es5.github.io/#callable">callable object</a>, add <var>CALLBACK</var> to <var>LIFECYCLE</var>, associated with the key <var>NAME</var>.</li>
</ol>
</div>

<p>To <dfn id="dfn-retrieve-callback">retrieve a callback named <em>name</em></dfn> for an <a href="http://dom.spec.whatwg.org/#concept-element">element</a>, the user agent <strong>must</strong> run the following steps:</p>
<div class="algorithm">
<dl>
<dt>Input</dt>
    <dd><var>NAME</var>, name of the callback</dd>
    <dd><var>ELEMENT</var>, the element</dd>
<dt>Output</dt>
    <dd><var>CALLBACK</var>, the callback</dd>
</dl>
<ol>
    <li>Let <var>DEFINITION</var> be <var>ELEMENT</var>'s <a href="#dfn-element-definition">definition</a></li>
    <li>If <var>DEFINITION</var> does not exist, let <var>CALLBACK</var> be <strong>null</strong> and <strong>stop</strong>.</li>
    <li>Let <var>CALLBACKS</var> be the <a href="#dfn-lifecycle-callbacks">lifecycle callbacks</a> from <var>DEFINITION</var>
    </li><li>Let <var>CALLBACK</var> be the callback, associated with the key <var>NAME</var> in <var>CALLBACKS</var>, or <strong>null</strong> if there is no such callback.</li>
</ol>
</div>

<p>Each <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#unit-of-related-similar-origin-browsing-contexts">unit of related similar-origin browsing contexts</a> has an associated <dfn id="dfn-lifecycle-callbacks-queue">lifecycle callbacks queue</dfn>, which is initially empty. Each item in the queue consists of the callback and the <a href="http://www.w3.org/TR/WebIDL/#dfn-callback-this-value">callback this value</a>.

</p><p>Also, each <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#unit-of-related-similar-origin-browsing-contexts">unit of related similar-origin contexts</a> has a <dfn id="dfn-running-lifecycle-callbacks">running lifecycle callbacks</dfn> flag, which <strong>must</strong> initially be <strong>false</strong>. It is used to prevent reentrant invocation of the algorithm to <a href="#dfn-invoke-lifecycle-callbacks">invoke lifecycle callbacks</a>.</p>

<p>To <dfn id="dfn-invoke-lifecycle-callbacks">invoke lifecycle callbacks</dfn>, a conforming user agent <strong>must</strong> run the following steps or their <a href="#dfn-processing-equivalence">equivalent</a>:</p>

<div class="algorithm">
<dl>
<dt>Input</dt>
    <dd><var>ENVIRONMENT</var>, the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#unit-of-related-similar-origin-browsing-contexts">unit of related similar-origin browsing contexts</a></dd>
<dt>Output</dt>
    <dd>None</dd>
</dl>
<ol>
    <li>Let <var>RUNNING</var> be the <a href="#dfn-running-lifecycle-callbacks">running lifecycle callbacks</a> flag</li>
    <li>If <var>RUNNING</var> is <strong>true</strong>, <strong>stop</strong>.</li>
    <li>Set <var>RUNNING</var> to <strong>true</strong>.</li>
    <li>Let <var>INVOCATIONS</var> be a copy of the <var>ENVIRONMENT</var>'s <a href="#dfn-lifecycle-callbacks-queue">lifecycle callbacks queue</a></li>
    <li>While <var>INVOCATIONS</var> is not empty:
    <ol>
        <li>Empty <var>ENVIRONMENT</var>'s <a href="#dfn-lifecycle-callbacks-queue">lifecycle callbacks queue</a>.
        </li><li>For each <var>INVOCATION</var> in <var>INVOCATIONS</var>:
        <ol>
            <li>Invoke callback in <var>INVOCATION</var> with the corresponding <a href="http://dev.w3.org/2006/webapi/WebIDL/#dfn-callback-this-value">callback this value</a></li>
        </ol></li>
        <li>Let <var>INVOCATIONS</var> be a copy of the <var>ENVIRONMENT</var>'s <a href="#dfn-lifecycle-callbacks-queue">lifecycle callbacks queue</a></li>
    </ol></li>
    <li>Set <var>RUNNING</var> to <strong>false</strong>.</li>
</ol>
</div>

<p>The following callbacks are recognized:</p>
<dl>
<dt>ready</dt>
    <dd>invoked after <a href="#dfn-custom-element">custom element</a> instance is created and its <a href="#dfn-element-definition">definition</a> is associated with the <a href="http://dom.spec.whatwg.org/#concept-document">document</a>. The actual timing of this callback is defined further in this specification.</dd>
<dt>inserted</dt>
    <dd>Unless specified otherwise, this callback <strong>must</strong> placed into the <a href="#dfn-lifecycle-callbacks-queue">lifecycle callbacks queue</a> with the <a href="http://www.w3.org/TR/WebIDL/#dfn-callback-this-value">callback this value</a> of the <a href="#dfn-custom-element">custom element</a> whenever <a href="#dfn-custom-element">custom element</a> is <a href="http://www.whatwg.org/specs/web-apps/current-work/#insert-an-element-into-a-document">inserted into a document</a>.</dd>
<dt>removed</dt>
    <dd>Unless specified otherwise, this callback <strong>must</strong> placed into the <a href="#dfn-lifecycle-callbacks-queue">lifecycle callbacks queue</a> with the <a href="http://www.w3.org/TR/WebIDL/#dfn-callback-this-value">callback this value</a> of the <a href="#dfn-custom-element">custom element</a> whenever <a href="#dfn-custom-element">custom element</a> is <a href="http://www.whatwg.org/specs/web-apps/current-work/#remove-an-element-from-a-document">removed from the document.</a>
</dd></dl>

<h2 id="registering-custom-elements">Registering Custom Elements</h2>

<p><dfn id="dfn-element-registration">Element registration</dfn> is a process of associating an <a href="#dfn-element-definition">element definition</a> with a <a href="http://dom.spec.whatwg.org/#concept-document">document</a>. An <a href="#dfn-element-definition">element definition</a> can only be <a href="#dfn-element-registration">registered</a> with one <a href="http://dom.spec.whatwg.org/#concept-document">document</a>. Once <a href="#dfn-element-registration">registered</a>, the <a href="#dfn-custom-element">custom element</a>'s <a href="http://www.w3.org/TR/WebIDL/#dfn-interface">interface</a> <strong>must</strong> be the <a href="http://dom.spec.whatwg.org/#concept-element-interface">element interface</a> for <a href="http://dom.spec.whatwg.org/#concept-element-local-name">local name</a> and <a href="http://dom.spec.whatwg.org/#concept-element-namespace">namespace</a> values of <a href="#dfn-custom-element-name">custom element name</a> and the <a href="http://dom.spec.whatwg.org/#concept-element-namespace">namespace</a> in <a href="#dfn-element-definition">custom element definition</a>, respectively.</p>

<p>Because <a href="#dfn-element-registration">element registration</a> can occur at any time, a <a href="#dfn-custom-element">custom element</a> could be created before it is <a href="#dfn-element-registration">registered</a>. Such <a href="#dfn-custom-element">custom element</a> instances are called <dfn id="dfn-unresolved-element">unresolved elements</dfn>. When an <a href="#dfn-unresolved-element">unresolved element</a> is created, <strong>and</strong> if its  <a href="http://dom.spec.whatwg.org/#concept-element-interface">element interface</a> was not defined by <a href="http://www.whatwg.org/specs/web-apps/current-work/">HTML</a> or <a href="http://www.whatwg.org/specs/web-apps/current-work/#other-applicable-specifications">other applicable specifications</a>, the <a href="#dfn-unresolved-element">unresolved element</a>'s <a href="http://dom.spec.whatwg.org/#concept-element-interface">element interface</a> <strong>must</strong> be:</p>
<ul>
    <li>the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#htmlelement"><code>HTMLElement</code></a>, if the <a href="http://dom.spec.whatwg.org/#concept-element-namespace">namespace</a> is <a href="http://www.w3.org/1999/xhtml">HTML Namespace</a>;</li>
    <li>the <a href="http://www.w3.org/TR/SVG/types.html#InterfaceSVGElement"><code>SVGElement</code></a>, if <a href="http://dom.spec.whatwg.org/#concept-element-namespace">namespace</a> is <a href="http://www.w3.org/2000/svg">SVG Namespace</a>; or</li>
    <li>unknown, otherwise.</li>
</ul>

<div class="informative">
The effect of this statement is that any element with a valid custom element name will have HTMLElement (or SVGElement) as element interface, rather than HTMLUnknownElement.
</div>

<p>Each <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#browsing-context">browsing context</a> has an associated <a href="http://en.wikipedia.org/wiki/Associative_array">map</a> of all instances of <a href="#dfn-unresolved-element">unresolved elements</a> for a given pair of <a href="#dfn-custom-element-name">custom element name</a> and <a href="http://dom.spec.whatwg.org/#concept-element-namespace">namespace</a>. This data structure is called the <dfn id="dfn-upgrade-candidates-map">upgrade candidates map</dfn> and is initially empty.</p>

<p>Whenever an <a href="#dfn-unresolved-element">unresolved element</a> is created, it <strong>must</strong> be added to the <a href="#dfn-upgrade-candidates-map">upgrade candidates map</a>.</p>

<p>As an <a href="#dfn-element-definition">element definition</a> is <a href="#dfn-element-registration">registered</a>, all corresponding <a href="#dfn-unresolved-element">unresolved elements</a> are upgraded using the <dfn id="dfn-element-upgrade">element upgrade algorithm</dfn>, which <strong>must</strong> be <a href="#dfn-processing-equivalence">equivalent</a> to running these steps:</p>

<div class="algorithm">
<dl>
<dt>Input</dt>
    <dd><var>CONTEXT</var>, a <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#browsing-context">browsing context</a></dd>
    <dd><var>DEFINITION</var>, an <a href="#dfn-element-definition">element definition</a></dd>
<dt>Output</dt>
    <dd>None</dd>
</dl>
<ol>
    <li>Let <var>TYPE</var> be the <a href="#dfn-custom-element-name">custom element name</a> in <var>DEFINITION</var></li>
    <li>Let <var>NAMESPACE</var> be the <a href="http://dom.spec.whatwg.org/#concept-element-namespace">namespace</a> in <var>DEFINITION</var></li>
    <li>Let <var>PROTOTYPE</var> be the <a href="#dfn-custom-element-prototype">custom element prototype</a> in <var>DEFINITION</var></li>
    <li>Let <var>MAP</var> be <var>CONTEXT</var>'s <a href="#dfn-upgrade-candidates-map">upgrade candidates map</a></li>
    <li>Let <var>CANDIDATES</var> be the list of all <a href="#dfn-unresolved-element">unresolved elements</a> for <var>TYPE</var> and <var>NAMESPACE</var> in <var>MAP</var></li>
    <li>For each item <var>ELEMENT</var> in <var>CANDIDATES</var>:
    <ol>
        <li>Set the value of the <code>[[Prototype]]</code> <a href="http://es5.github.com/#x8.6.2">internal property</a> of <var>ELEMENT</var> to <var>PROTOTYPE</var></li>
        <li>Let <var>READY</var> be the result of <a href="#dfn-retrieve-callback">retrieving a callback</a> named <em>ready</em>.</li>
        <li>Place <var>READY</var> and <a href="http://www.w3.org/TR/WebIDL/#dfn-callback-this-value">callback this value</a> of <var>ELEMENT</var> into the <a href="#dfn-lifecycle-callbacks-queue">lifecycle callbacks queue</a>.</li>
        <li>If <var>ELEMENT</var> is <a href="http://www.whatwg.org/specs/web-apps/current-work/#in-a-document">in a document</a>:
        <ol>
            <li>Let <var>INSERTED</var> be the result of <a href="#dfn-retrieve-callback">retrieving a callback</a> named <em>inserted</em>.</li>
            <li>Place <var>INSERTED</var> and <a href="http://www.w3.org/TR/WebIDL/#dfn-callback-this-value">callback this value</a> of <var>ELEMENT</var> into the <a href="#dfn-lifecycle-callbacks-queue">lifecycle callbacks queue</a>.</li>
        </ol></li>
    </ol></li>
    <li>Set <var>CANDIDATES</var> to empty list</li>
</ol>
</div>

<p>The <dfn id="dfn-document-register"><code>register</code></dfn> method of the <a href="http://www.w3.org/TR/domcore/#document">Document</a> interface provides a way to <a href="#dfn-element-registration">register</a> a <a href="#dfn-custom-element">custom element</a> and returns its <a href="#dfn-custom-element-constructor">custom element constructor</a>.</p>

<pre><code>
partial interface <a href="http://www.w3.org/TR/domcore/#document">Document</a> {
    Function <a href="#dfn-document-register">register</a>(DOMString <a href="#var-document-register-name">name</a>, optional <a href="#api-element-registration-options">ElementRegistrationOptions</a> options);
};

dictionary <dfn id="api-element-registration-options">ElementRegistrationOptions</dfn> {
     object? <a href="#var-options-prototype">prototype</a> = null;
};

</code></pre>

<p>When called, the <a href="#dfn-document-register"><code>register</code></a> method <strong>must</strong> run these steps:</p>

<div class="algorithm">
<dl>
<dt>Input</dt>
    <dd><var>ENVIRONMENT</var>, the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#unit-of-related-similar-origin-browsing-contexts">unit of related similar-origin browsing contexts</a></dd>
    <dd><var>DOCUMENT</var>, the <a href="http://dom.spec.whatwg.org/#context-object">context object</a> of the method</dd>
    <dd><var id="var-document-register-name">NAME</var>, the <a href="#dfn-custom-element-name">custom element name</a> of the element being registered</dd>
    <dd><var id="var-options-prototype">PROTOTYPE</var>, the <a href="#dfn-custom-element-prototype">custom element prototype</a>, optional</dd>
<dt>Output</dt>
    <dd><var>CONSTRUCTOR</var>, the <a href="#dfn-custom-element-constructor">custom element constructor</a></dd>
</dl>
<ol>
    <li>If <var>NAME</var> is an invalid <a href="#dfn-custom-element-name">custom element name</a>, throw an <a href="http://dom.spec.whatwg.org/#invalidcharactererror"><code>InvalidCharacterError</code></a> and <strong>stop</strong>.</li>
    <li>Let <var>NAMESPACE</var> be <a href="http://www.w3.org/1999/xhtml">HTML Namespace</a></li>
    <li>Let <var>TYPE</var> be <var>NAME</var></li>
    <li>If <var>PROTOTYPE</var> is <strong>null</strong>, let <var>PROTOTYPE</var> be the result of invoking <a href="http://es5.github.com/#x15.2.3.5"><code>Object.create</code></a> with <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#htmlelement"><code>HTMLElement</code></a>'s <a href="http://www.w3.org/TR/WebIDL/#dfn-interface-prototype-object">interface prototype object</a> as only argument</li>
    <li>Otherwise:
    <ol>
        <li>If <var>PROTOTYPE</var> and <var>DOCUMENT</var> are from different <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#browsing-context">browsing contexts</a>, throw a <a href="http://dom.spec.whatwg.org/#notsupportederror"><code>NotSupportedError</code></a> and <strong>stop</strong>.</li>
        <li>Let <var>INTERFACE</var> be <var>PROTOTYPE</var>'s <a href="http://www.w3.org/TR/WebIDL/#dfn-interface">interface</a></li>
        <li>If <var>INTERFACE</var> <a href="http://www.w3.org/TR/WebIDL/#dfn-inherit">inherits</a> from <a href="http://www.w3.org/TR/SVG/types.html#InterfaceSVGElement"><code>SVGElement</code></a>, set <var>NAMESPACE</var> to <a href="http://www.w3.org/2000/svg">SVG Namespace</a></li>
        <li>Otherwise, if <var>INTERFACE</var> does not <a href="http://www.w3.org/TR/WebIDL/#dfn-inherit">inherit</a> from <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#htmlelement"><code>HTMLElement</code></a>, <a href="http://dom.spec.whatwg.org/#concept-throw">throw</a> a <a href="http://dom.spec.whatwg.org/#namespaceerror"><code>NamespaceError</code></a> and <strong>stop</strong>.</li>
        <li>Let <var>BASE</var> be <var>INTERFACE</var>'s <a href="http://www.w3.org/TR/WebIDL/#dfn-inherited-interfaces">inherited interface</a> that is nearest to <var>BASE</var> in the <a href="http://es5.github.com/#x4.2.1">prototype chain</a> <strong>and</strong> that is an <a href="http://dom.spec.whatwg.org/#concept-element-interface">element interface</a></li>
        <li>If <var>BASE</var> is not <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#htmlelement"><code>HTMLElement</code></a> or <a href="http://www.w3.org/TR/SVG/types.html#InterfaceSVGElement"><code>SVGElement</code></a>, let <var>NAME</var> be the <a href="">local name</a>, associated with <var>BASE</var> <a href="http://dom.spec.whatwg.org/#concept-element-interface">element interface</a></li>
    </ol></li>
    <li>If <var>DOCUMENT</var> is an <a href="http://dom.spec.whatwg.org/#html-document">HTML document</a>, <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#converted-to-ascii-lowercase">convert</a> both <var>NAME</var> and <var>TYPE</var> to lowercase</li>
    <li>If there already exists a <a href="#dfn-element-definition">definition</a> with the same <var>TYPE</var>, throw a <a href="http://dom.spec.whatwg.org/#notsupportederror"><code>NotSupportedError</code></a> and <strong>stop</strong>.</li>
    <li>Let <var>LIFECYCLE</var> be <a href="#dfn-lifecycle-callbacks">lifecycle callbacks</a></li>
    <li><a href="#dfn-transfer-callback">Transfer callback</a> named <em>ready</em> to <var>LIFECYCLE</var> from property named <em>readyCallback</em> on <var>PROTOTYPE</var></li>
    <li><a href="#dfn-transfer-callback">Transfer callback</a> named <em>inserted</em> to <var>LIFECYCLE</var> from property named <em>insertedCallback</em> on <var>PROTOTYPE</var></li>
    <li><a href="#dfn-transfer-callback">Transfer callback</a> named <em>removed</em> to <var>LIFECYCLE</var> from property named <em>removedCallback</em> on <var>PROTOTYPE</var></li>
    <li>Let <var>DEFINITION</var> be the set of (<var>TYPE</var>, <var>NAME</var>, <var>NAMESPACE</var>, <var>PROTOTYPE</var>, <var>LIFECYCLE</var>)</li>
    <li><a href="#dfn-element-registration">Register</a> the <var>DEFINITION</var> with <var>DOCUMENT</var></li>
    <li>Run <a href="#dfn-element-upgrade">element upgrade algorithm</a> with <var>DOCUMENT</var>'s <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#browsing-context">browsing context</a> and <var>DEFINITION</var> as arguments</li>
    <li><a href="#dfn-invoke-lifecycle-callbacks">Invoke lifecycle callbacks</a> with <var>ENVIRONMENT</var> as argument</li>
    <li>Return result of running <a href="#dfn-custom-element-constructor-generation">custom element constructor generation algorithm</a> with <var>PROTOTYPE</var> as argument.</li>
</ol>
</div>

<div class="informative">
<p><code>ElementRegistrationOptions</code> is an abstraction that enables using function objects and ES6 classes as the second argument of <code>document.register</code> method.</p>
</div>

<div class="informative">
<p>The element upgrade and invoking lifecycle callbacks is intentionally decoupled to provide slightly more sensible outcomes of callbacks trying to access methods and properties of custom elements of the same kind. Also, because of when lifecycle callbacks are added to the lifecycle callbacks queue, the queue should be empty when <code>document.register</code> is invoked.</p>
</div>

<div class="informative">
<p>In order to  <a href="#dfn-element-registration">register</a> a <a href="#dfn-custom-element">custom element</a> with a prototype, other than <code>HTMLElement</code> or <code>SVGElement</code>, the caller of <code>document.register</code> has to first build a proper prototype object that inherits from <code>HTMLElement</code>. Here's a simple example of how one could do this:</p>
<pre><code class="prettyprint">
document.register('x-foo', {
    prototype: Object.create(HTMLParagraphElement.prototype, {
        firstMember: {
            get: function() { return foo; },
            enumerable: true,
            configurable: true
        },
        // specify more members for your prototype.
        // ...
    })
});

</code></pre>
</div>

<h3 id="unresolved-element-pseudoclass">Unresolved Element Pseudoclass</h3>

<p>The <code>:unresolved</code> <a href="http://www.w3.org/TR/CSS2/selector.html#pseudo-elements">pseudoclass</a> <strong>must</strong> match all <a href="#dfn-unresolved-element">unresolved elements</a>.</p>

<div class="informative">
<p>The <code>:unresolved</code> <a href="http://www.w3.org/TR/CSS2/selector.html#pseudo-elements">pseudoclass</a> could be used to mitigate the <a href="http://en.wikipedia.org/wiki/Flash_of_unstyled_content">Flash of Unstyled Content</a> (FOUC) issues with <a href="#dfn-custom-element">custom elements</a>.
</p></div>

<h2 id="instantiating-custom-elements">Instantiating Custom Elements</h2>

<p>The <a href="#dfn-custom-element-name">custom element name</a> is given to a <a href="#dfn-custom-element">custom element</a> at the time of its instantation in one of the two ways:</p>
<ol>
    <li>As the <a href="http://dom.spec.whatwg.org/#concept-element-local-name">local name</a> of the <a href="#dfn-custom-element">custom element</a>. These types of <a href="#dfn-custom-element-name">custom element names</a> are called <dfn id="dfn-custom-tag">custom tags</dfn>.</li>
    <li>As the value of the <code>is</code> <a href="http://dom.spec.whatwg.org/#concept-named-attribute">attribute</a> of the <a href="#dfn-custom-element">custom element</a>. <a href="#dfn-custom-element-name">Custom element names</a> given this way are called <dfn id="dfn-type-extension">type extensions</dfn>.</li>
</ol>

<p>After a <a href="#dfn-custom-element">custom element</a> is instantiated, changing the value of the <code>is</code> <a href="http://dom.spec.whatwg.org/#concept-named-attribute">attribute</a> <strong>must not</strong> affect this element's <a href="#dfn-custom-element-name">custom element name</a>.</p>

<p>If both types of <a href="#dfn-custom-element-name">custom element names</a> are provided at the time of element's instantiation, the <a href="#dfn-custom-tag">custom tag</a> <strong>must</strong> win over the <a href="#dfn-type-extension">type extension</a>.

</p><p>All <a href="#dfn-custom-element">custom elements</a> <strong>must</strong> be constructable with a <a href="http://www.w3.org/TR/WebIDL/#dfn-function-object">function object</a>, called <dfn id="dfn-custom-element-constructor">custom element constructor</dfn>. This constructor <strong>must</strong> be created with the <dfn id="dfn-custom-element-constructor-generation">custom element constructor generation algorithm</dfn>, which <strong>must</strong> be <a href="#dfn-processing-equivalence">equivalent</a> to running these steps:</p>
<div class="algorithm">
<dl>
<dt>Input</dt>
    <dd><var>PROTOTYPE</var>, the <a href="#dfn-custom-element-prototype">custom element prototype</a>.</dd>
<dt>Output</dt>
    <dd><var>CONSTRUCTOR</var>, the <a href="#dfn-custom-element-constructor">custom element constructor</a></dd>
</dl>
<ol>
    <li>If <var>PROTOTYPE</var> is already an <a href="http://www.w3.org/TR/WebIDL/#dfn-interface-prototype-object">interface prototype object</a> for any <a href="http://www.w3.org/TR/WebIDL/#dfn-interface-object">interface object</a> <strong>or</strong> <var>PROTOTYPE</var> has a <a href="http://es5.github.io/#x8.6.1">non-configurable</a> property named <code>constructor</code>, throw a <a href="http://dom.spec.whatwg.org/#notsupportederror"><code>NotSupportedError</code></a> and <strong>stop</strong>.</li>
    <li>Let <var>DEFINITION</var> be an <a href="#dfn-element-definition">element definition</a> that has <var>PROTOTYPE</var> as <a href="#dfn-custom-element-prototype">custom element prototype</a></li>
    <li>Let <var>CONSTRUCTOR</var> be the <a href="http://www.w3.org/TR/WebIDL/#dfn-interface-object">interface object</a> whose <a href="http://www.w3.org/TR/WebIDL/#dfn-interface-prototype-object">interface prototype object</a> is <var>PROTOTYPE</var> and when called as a constructor, executes these steps:
    <ol>
        <li>Let <var>TYPE</var> be the <a href="#dfn-custom-element-name">custom element name</a> in <var>DEFINITION</var></li>
        <li>Let <var>NAME</var> be the <a href="http://dom.spec.whatwg.org/#concept-element-local-name">local name</a> in <var>DEFINITION</var></li>
        <li>Let <var>NAMESPACE</var> be the <a href="http://dom.spec.whatwg.org/#concept-element-namespace">namespace</a> in <var>DEFINITION</var></li>
        <li>Let <var>ELEMENT</var> be the <a href="http://dom.spec.whatwg.org/#context-object">context object</a></li>
        <li>Set <var>ELEMENT</var>'s <a href="http://dom.spec.whatwg.org/#concept-element-local-name">local name</a> to <var>NAME</var>, <a href="http://dom.spec.whatwg.org/#concept-element-namespace">namespace</a> to the <var>NAMESPACE</var>, and <a href="http://dom.spec.whatwg.org/#concept-node-document">node document</a> to the <a href="http://dom.spec.whatwg.org/#concept-document">document</a> with which <var>DEFINITION</var> is registered</li>
        <li>If <var>TYPE</var> is not the same as <var>NAME</var>, set the value of <var>ELEMENT</var>'s <code>is</code> <a href="http://dom.spec.whatwg.org/#concept-named-attribute">attribute</a> to <var>TYPE</var></li>
        <li>Run the <a href="#dfn-element-initialization">element initialization algorithm</a> with <var>ELEMENT</var> as argument</li>
        <li>Return <var>ELEMENT</var>.</li>
    </ol></li>
</ol>
</div>

<div class="monkeypatch" id="monkeypatch-create-element">

<p>To allow creating both <a href="#dfn-custom-tag">custom tag</a> and <a href="#dfn-type-extension">type extension</a>-style <a href="#dfn-custom-element">custom elements</a>, the <a href="http://dom.spec.whatwg.org/#dom-document-createelement"><code>createElement</code></a> or <a href="http://dom.spec.whatwg.org/#dom-document-createelementns"><code>createElementNS</code></a> methods have an optional <code>typeExtension</code> argument:</p>

<pre><code>
partial interface <a href="http://www.w3.org/TR/domcore/#document">Document</a> {
    <a href="http://dom.spec.whatwg.org/#element">Element</a> createElement(DOMString localName, optional DOMString typeExtension);
    <a href="http://dom.spec.whatwg.org/#element">Element</a> createElementNS(DOMString? namespace, DOMString qualifiedName, optional DOMString typeExtension);
};
</code></pre>

<p>Instead of step 3 in <a href="http://dom.spec.whatwg.org/#dom-document-createelement"><code>createElement</code></a> and step 9 in <a href="http://dom.spec.whatwg.org/#dom-document-createelementns"><code>createElementNS</code></a> (the steps that determine <a href="http://dom.spec.whatwg.org/#concept-element-interface">element interface</a>, both methods <strong>must</strong> run the following 
steps:</p>
<ol>
    <li>Let <var>TYPE</var> be <em>typeExtension</em>, or <em>localName</em> if <em>typeExtension</em> is not present</li>
    <li>If an <a href="#dfn-element-definition">element definition</a> with matching <em>localName</em>, <em>namespace</em>, and <var>TYPE</var> is <strong>not</strong> <a href="#dfn-element-registration">registered</a> with <em>token</em>'s document, set <var>TYPE</var> to <em>localName</em></li>
    <li>Let <em>interface</em> be the <a href="http://dom.spec.whatwg.org/#concept-element-interface">element interface</a> for <var>TYPE</var> as <a href="http://dom.spec.whatwg.org/#concept-element-local-name">local name</a> and <em>namespace</em> (<a href="http://www.w3.org/1999/xhtml">HTML Namespace</a> for <a href="http://dom.spec.whatwg.org/#dom-document-createelement"><code>createElement</code></a>)</li>
</ol>

<p>Additionally, both <a href="http://dom.spec.whatwg.org/#dom-document-createelement"><code>createElement</code></a> or <a href="http://dom.spec.whatwg.org/#dom-document-createelementns"><code>createElementNS</code></a> methods <strong>must</strong> run the following steps just <em>before</em> returning the result:</p>
<ol>
    <li>If <var>TYPE</var> is not the same as <em>localName</em>, set the value of <var>ELEMENT</var>'s <code>is</code> <a href="http://dom.spec.whatwg.org/#concept-named-attribute">attribute</a> to <var>TYPE</var></li>
    <li>Run <a href="#dfn-element-initialization">element initialization algorithm</a> with the newly created <a href="http://dom.spec.whatwg.org/#concept-element">element</a></li>
</ol>
</div>

<p>The <dfn id="dfn-element-initialization">element initialization algorithm</dfn> <strong>must</strong> be <a href="#dfn-processing-equivalence">equivalent</a> to running these steps:</p>

<div class="algorithm">
<dl>
<dt>Input</dt>
    <dd><var>ELEMENT</var>, an <a href="http://www.w3.org/TR/domcore/#concept-element">element</a> being initialized</dd>
<dt>Output</dt>
    <dd>None</dd>
</dl>
<ol>
    <li>Let <var>DEFINITION</var> be <var>ELEMENT</var>'s <a href="#dfn-element-definition">definition</a></li>
    <li>Let <var>READY</var> be the result of <a href="#dfn-retrieve-callback">retrieving a callback</a> named <em>ready</em></li>
    <li>If it is not <code>null</code>, invoke <var>READY</var> callback with <a href="http://www.w3.org/TR/WebIDL/#dfn-callback-this-value">callback this value</a> of <var>ELEMENT</var></li>
</ol>
</div>

<h2 id="serializing-and-parsing">Serializing and Parsing Custom Elements in HTML</h2>

<p>To enable instantiating <a href="#dfn-custom-element">custom elements</a> during <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/tree-construction.html#tree-construction">tree construction</a>, a conforming UA <strong>must</strong> run these steps when <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/tree-construction.html#create-an-element-for-the-token">creating an element for a token</a>:</p>

<div class="monkeypatch">
<dl>
<dt>Input</dt>
    <dd><var>DOCUMENT</var>, the <a href="http://www.w3.org/TR/domcore/#concept-document">document</a> in which the element is being created</dd>
    <dd><var>TOKEN</var>, token tag name</dd>
    <dd><var>NAMESPACE</var>, token <a href="http://dom.spec.whatwg.org/#concept-element-namespace">namespace</a></dd>
<dt>Output</dt>
    <dd><var>ELEMENT</var>, an element</dd>
</dl>
<ol>
    <li>Let <var>NAME</var> be the tag name of the <em>token</em></li>
    <li>Let <var>NAMESPACE</var> be the <em>token</em>'s namespace</li>
    <li>Let <var>TYPE</var> be the value of <code>is</code> attribute for the <em>token</em> or <var>NAME</var>, if this attribute is not present</li>
    <li>If <var>DOCUMENT</var> is an <a href="http://dom.spec.whatwg.org/#html-document">HTML document</a>, <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#converted-to-ascii-lowercase">convert</a> both <var>NAME</var> and <var>TYPE</var> to lowercase</li>
    <li>If an <a href="#dfn-element-definition">element definition</a> with matching <var>NAME</var>, <var>NAMESPACE</var>, and <var>TYPE</var> is <strong>not</strong> <a href="#dfn-element-registration">registered</a> with <em>token</em>'s document, set <var>TYPE</var> to <var>NAME</var></li>
    <li>Let <var>ELEMENT</var> be the result of creating a node implementing the interface appropriate for the element type corresponding to <var>TYPE</var> and <var>NAMESPACE</var></li>
    <li>Let <var>READY</var> be the result of <a href="#dfn-retrieve-callback">retrieving a callback</a> named <em>ready</em>.</li>
    <li>Place <var>READY</var> and <a href="http://www.w3.org/TR/WebIDL/#dfn-callback-this-value">callback this value</a> of <var>ELEMENT</var> at the front of the <a href="#dfn-lifecycle-callbacks-queue">lifecycle callbacks queue</a>.</li>
</ol>
</div>

<div class="informative">
<p>This modification to <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/tree-construction.html#create-an-element-for-the-token">creating an element for a token</a> has the consequence of <a href="#dfn-custom-element">custom elements</a> being created when <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/parsing.html#parsing">parsing HTML documents</a> or <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-end.html#html-fragment-parsing-algorithm">fragments</a>.</p>
</div>

<p>In addition, just before the user agent is to <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#perform-a-microtask-checkpoint">perform a microtask checkpoint</a>, the user agent <strong>must</strong> <a href="#dfn-invoke-lifecycle-callbacks">invoke lifecycle callbacks</a> for the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#unit-of-related-similar-origin-browsing-contexts">unit of related similar-origin browsing contexts</a> to which the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#script's-browsing-context">scripts' browsing context</a> belongs.</p>

<p>The <a href="#dfn-custom-element">custom elements</a> <strong>must</strong> be serialized like <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-end.html#serializing-html-fragments">any HTML elements</a>.</p>

<h2 id="declaring-custom-elements">Declaring Custom Elements</h2>

<p><span class="fixme">Specify how custom elements are defined declaratively.</span></p>

<!--

<h2 id="elements-and-dom-interfaces">Elements and DOM Interfaces</h2>

<h3 id="the-element-element">The <code>element</code> HTML element</h3>

<dl>
<dt>Context</dt>
<dd>Where <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#flow-content-0">flow content</a> is expected.</dd>
<dt>Content model</dt>
<dd><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#metadata-content">Metadata content</a></dd>
<dt>Children</dt>
<dd>One <code>template</code> element and zero or more <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#the-script-element"><code>script</code></a> elements</dd>
<dt>Content attributes</dt>
<dd><a href="http://dev.w3.org/html5/spec/Overview.html#global-attributes">Global attributes</a></dd>
<dd><a href="#dfn-element-constructor"><code>constructor</code></a></dd>
<dd><a href="#dfn-element-extends"><code>extends</code></a></dd>
<dd><a href="#dfn-element-name"><code>name</code></a></dd>
<dt>DOM Interface</dt>
<dd>
    <pre><code class="prettyprint">
interface <dfn id="api-html-element-element">HTMLElementElement</dfn> : <a href="http://dev.w3.org/html5/spec/Overview.html#htmlelement">HTMLElement</a> {
    attribute DOMString <a href="#dfn-html-element-element-constructor-name">constructorName</a>;
    attribute DOMString <a href="#dfn-html-element-element-extends">extends</a>;
    attribute DOMString <a href="#dfn-html-element-element-name">name</a>;
    readonly attribute Function <a href="#dfn-html-element-element-generated-constructor">generatedConstructor</a>;
};</code></pre>
</dd>
</dl>
<p>The <a href="#the-element-element"><code>element</code></a> HTML element represents a <a href="#dfn-element-definition">definition</a> of a <a href="#dfn-custom-element">custom element</a>.</p>

<p>The <dfn id="dfn-element-extends">extends</dfn> attribute specifies the name of the HTML element or the <a href="#dfn-custom-element-name">custom element name</a>, which is <a href="#dfn-extend-dom-element">extended</a> by the defined <a href="#dfn-custom-element">custom element</a>.</p>

<p>The <dfn id="dfn-element-name">name</dfn> attribute provides the <a href="#dfn-custom-element-name">name</a> of the new <a href="#dfn-custom-element">custom element</a>.</p>

<p>The <dfn id="dfn-element-constructor">constructor</dfn> attribute gives the name of the <a href="#dfn-custom-element-constructor">custom element constructor</a>. The value of the attribute <strong>must</strong> be a valid <a href="http://ecma-international.org/ecma-262/5.1/#sec-7.6">IdentifierName</a>. If the value is not a valid <a href="http://ecma-international.org/ecma-262/5.1/#sec-7.6">IdentifierName</a>, the <a href="#dfn-element-definition">definition</a> state must be set to <a href="#dfn-invalid-definition">invalid</a>.</p>

<p>The <dfn id="dfn-html-element-element-constructor-name">constructorName</dfn> IDL attribute <strong>must</strong> <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-dom-interfaces.html#reflect">reflect</a> the <a href="#dfn-element-constructor">constructor</a> content attribute.</p>

<p>The <dfn id="dfn-html-element-element-extends">extends</dfn> and <dfn id="dfn-html-element-element-name">name</dfn> IDL attributes <strong>must</strong> <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same name.</p>

<p>The <dfn id="dfn-html-element-element-generated-constructor">generatedConstructor</dfn> IDL attribute <strong>must</strong> return <a href="#dfn-custom-element">custom element</a>'s <a href="#dfn-custom-element-constructor">custom element constructor</a>.</p>

<div class="monkeypatch">
This part of the specification describes changes to behavior of <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#the-script-element"><code>script</code></a> element in <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/">HTML</a> specification.
</div>

<p>A <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#the-script-element"><code>script</code></a> element that is a child of the <code><a href="#the-element-element">element</a></code> element has these additional requirements:</p>
<ol>
    <li>The actual values of <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#attr-script-async"><code>async</code></a> and <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#attr-script-defer"><code>defer</code></a> attributes <strong>must</strong> be ignored</li>
    <li>When the script is being <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#prepare-a-script">prepared</a>:
    <ol>
        <li>The element <strong>must</strong> be added to the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#list-of-scripts-that-will-execute-in-order-as-soon-as-possible">set of scripts that will execute as soon as possible</a> of the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#document"><code>Document</code></a>, of the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#the-script-element"><code>script</code></a> element at the time the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#prepare-a-script">prepare a script</a> algorithm started.</li>
        <li>The user agent then <strong>must</strong> <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#queue-a-task">queue</a> a <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#concept-task">task</a> to to <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#execute-the-script-block">execute the script block</a> and then remove the element from the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#set-of-scripts-that-will-execute-as-soon-as-possible">set of scripts that will execute as soon as possible</a>. The <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#task-source">task source</a> is the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#networking-task-source">networking task source</a> if the element has the <a href=""><code>src</code></a> attribute, and <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#dom-manipulation-task-source">DOM manipulation task source</a> otherwise.</p></li>
    </ol></li>
    <li><p>The <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#the-script-block's-source">script's block source</a> <strong>must</strong> contain valid JavaScript code which, when parsed, would match the <a href="http://ecma-international.org/ecma-262/5.1/#sec-13">FunctionBody</a> production after the <a href="http://ecma-international.org/ecma-262/5.1/#sec-7.9">automatic semicolon insertion</a>.<p>

    <p>When <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#the-script-block's-source">creating a script</a> from a node that is a child of the <code><a href="#the-element-element">element</a></code> element, the user agent must run the following steps:</p>
    <div class="algorithm">
    <dl>
    <dt>Input</dt>
        <dd><var>ELEMENT</var>, the <a href="#the-element-element"><code>element</code></a> element</dd>
        <dd><var>SOURCE</var>, the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#the-script-block's-source">script's block source</a>.</dd>
        <dd><var>GLOBAL</var>, the <a href="http://ecma-international.org/ecma-262/5.1/#sec-10.2.3">global environment</a></dd>
    <dt>Output</dt>
        <dd><var>SCRIPT</var>, the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#concept-script">script</a> to be executed</dd>
    </dl>
    <ol>
        <li>Let <var>DOCUMENT</var> be the <var>ELEMENT</var>'s <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#document"><code>Document</code></a></dd>
        <li>If <var>SOURCE</var> is not parsable as <a href="http://ecma-international.org/ecma-262/5.1/#sec-13">FunctionBody</a> or if parsing detects an <a href="http://ecma-international.org/ecma-262/5.1/#sec-16">early error</a>, then <a href="#dfn-invalid-definition">set the definition state to invalid</a> and <strong>stop</strong>.</li>
        <li>Let <var>STRICT</var> be <strong>true</strong> if <var>SOURCE</var> begins with a <a href="http://ecma-international.org/ecma-262/5.1/#sec-14.1">Directive Prologue</a> that contains a <a href="http://ecma-international.org/ecma-262/5.1/#sec-14.1">Use Strict Directive</a>, and <strong>false</strong> otherwise</li>
        <li>Let <var>DOCUMENTSCOPE</var> be the result of running <a href="http://ecma-international.org/ecma-262/5.1/#sec-10.2.2.3">NewObjectEnvironment</a> with parameters <em>O</em> as <var>DOCUMENT</var> and <em>E</em> as <var>GLOBAL</var>.</li>
        <li>Let <var>SCOPE</var> be the result of running <a href="http://ecma-international.org/ecma-262/5.1/#sec-10.2.2.3">NewObjectEnvironment</a> with parameters <em>O</em> as <var>ELEMENT</var> and <em>E</em> as <var>DOCUMENTSCOPE</var>.</li>
        <li>Let <var>ENVIRONMENT</var> be a new <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#script-execution-environment">script execution environment</a> for JavaScript.</li>
        <li>Let <var>FUNCTION</var> be the result of <a href="http://ecma-international.org/ecma-262/5.1/#sec-13.2">creating a function object</a> in <var>ENVIRONMENT</var> with parameters <em>FormalParameterList</em> empty, <em>FunctionBody</em> as <var>SOURCE</var>, <em>Scope</em> as <var>SCOPE</var>, and <em>Strict</em> as <var>STRICT</var></li>
        <li>Return <var>SCRIPT</var> with:
        <ol>
            <li><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#script-execution-environment">script execution environment</a> as <var>ENVIRONMENT</var></li>
            <li><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#list-of-code-entry-points">list of code entry points</a> consisting on <var>FUNCTION</var> as the only entry, and</li>
            <li>the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#script's-global-object>">script's global object</a>, the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#script's-browsing-context">script's browsing context</a>, the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#script's-document">script's document</a>, <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#script's-url-character-encoding">script's URL character encoding</a>, and the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#script's-base-url">script's base URL</a> from the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#the-script-settings-determined-from-the-node">the script settings determined on</a> <var>ELEMENT</var></li>
        </ol></li>
    </ol>
    </div></li>
</ol>

<div class="informative">The term "JavaScript" is used to refer to ECMA262, rather than the official term ECMAScript, since the term JavaScript is more widely known.</div>

<h2 id="other-languages">Supporting Other Languages</h2>

<p><span class="fixme">Explain how inheritance in custom elements can be extended to other languages.</span></p>

-->

</section>

<h2 id="acknowledgements">Acknowledgements</h2>

<p><span class="vcard">David Hyatt</span> developed <a href="http://dev.w3.org/2006/xbl2/">XBL 1.0</a>, and <span class="vcard">Ian Hickson</span> co-wrote <a href="http://dev.w3.org/2006/xbl2/">XBL 2.0</a>. These documents provided tremendous insight into the problem of behavior attachment and greatly influenced this specification.</p>

<p><span class="vcard">Alex Russell</span> and his considerable forethought triggered a new wave of enthusiasm around the subject of behavior attachment and how it can be applied practically on the Web.</p>

<p><span class="vcard">Dominic Cooney</span>, <span class="vcard">Hajime Morrita</span>, and <span class="vcard">Roland Steiner</span> worked tirelessly to scope the problem within the confines of the Web platform and provided a solid foundation for this document.</p>

<p>The editor would also like to thank <span class="vcard">Alex Komoroske</span>, <span class="vcard">Anne van Kesteren</span>, <span class="vcard">Boris Zbarsky</span>, <span class="vcard">Daniel Buchner</span>, <span class="vcard">Edward O'Connor</span>, <span class="vcard">Erik Arvidsson</span>, <span class="vcard">Elliott Sprehn</span>, <span class="vcard">Hayato Ito</span>, <span class="vcard">Jonas Sicking</span>, <span class="vcard">Olli Pettay</span>, <span class="vcard">Rafael Weinstein</span>, <span class="vcard">Scott Miles</span>, <span class="vcard">Steve Orvell</span>, <span class="vcard">Tab Atkins</span>, and <span class="vcard">William Chen</span> for their comments and contributions to this specification.</p>

<p>This list is too short. There's a lot of work left to do. Please contribute by reviewing and filing bugs—and don't forget to ask the editor to add your name into this section.</p>



</body></html>
